//
//  "$Id: Comm.h 91860 2012-12-08 09:18:30Z li_weijun $"
//
//  Copyright (c)1992-2007, ZheJiang Dahua Technology Stock CO.LTD.
//  All Rights Reserved.
//
//	Description:	
//	Revisions:		Year-Month-Day  SVN-Author  Modification
//

#ifndef __COMM_API_H__
#define __COMM_API_H__

#include "Types.h"
#include "Defs.h"

#ifdef __cplusplus
extern "C" {
#endif

/// \defgroup CommAPI API Comm
/// 标准的串口通讯接口，支持RS232,RS485,前面板等设备
/// \n 调用流程图:
/// \code
///    =========================================
///                   |                         
///              createCommPort                  
///                   |                         
///                addRef                  
///       +-----------|	          
///       |      setAttribute  	
///       |       ssConsole     	
///       |           |           	 
///       |         open    
///       | +---------|      
///       | |       read    
///       | |       write   
///       | |       purge   
///       | +---------|      	
///       |         close   
///       +-----------|
///                release                  
///                   |                         
///    =========================================
/// \endcode
/// @{

/// 串口操作中断类型
typedef enum CommPurgeFlags
{
	commPurgeTxAbort = 0x0001,	///< 中止写操作
	commPurgeRxAbort = 0x0002,	///< 中止读操作
	commPurgeTxClear = 0x0004,	///< 清空输出缓冲
	commPurgeRxClear = 0x0008 	///< 清空输入缓冲
} CommPurgeFlags;

/// 串口停止位类型
typedef enum CommStopBit
{
	commOneStopBit = 0,		///< 1 stop bit
	commOne5StopBits,		///< 1.5 stop bit
	commTwoStopBits			//< 2 stop bit
} CommStopBit;

/// 串口校验位类型
typedef enum CommParityType 
{
	commNoParity = 0,	///< No parity
	commOddParity,		///< Odd parity
	commEvenParity,		///< Even parity
	commMarkParity,		///< Mark parity
	commSpaceParity		///< Space parity
} CommParityType;

/// 特殊串口标志
typedef enum CommSpecialFlag
{
	commNormal = 0,
	commRedApple
} CommSpecialFlag;

/// 串口模式
typedef enum CommMode
{
	commFullDuplex = 0,	///< 全双工
	commSemiDuplex,		///< 半双工
} CommMode;

/// 串口能力结构，128字节
typedef struct CommCaps
{
	CommMode mode;		///< 工作模式
	int internal;		///< 是否为内部使用，比如内置云台设备
	uchar bus;			///< 串口总线类型，0:RS-232，1:RS-485
	char reserved[119];	///< 保留字节
} CommCaps;

/// 串口属性结构，128字节
typedef struct CommAttribute
{
	int		baudrate;	///< 实际的波特率值。		
	char	dataBits;	///< 实际的数据位 取值为5,6,7,8	
	char	parity;		///< 奇偶校验选项，取CommParityType类型的枚举值。	
	char	stopBits;	///< 停止位数，取CommStopBit类型的枚举值。	
	char	flag;		///< 特殊串口标志，取CommSpecialFlag类型的枚举值。
	int  	timeOut;    ///< 读超时时间， 0：阻塞  >0：超时时间，单位：百毫秒
	char	readMode;	///< 读模式，0：读到数据返回 1：读到指定长度数据返回
	char	reserved1[3];
	int 	reserved[28];///< 保留字节
} CommAttribute;

/// 串口接口，512字节
typedef struct CommPort
{
	/// 底层私有数据
	void *priv;


	/// 增加接口引用
	int (*addRef)(struct CommPort *thiz);


	/// 释放接口
	int (*release)(struct CommPort *thiz);


	/// 打开串口设备，打开后标准输入输出不能使用串口。
	/// 
	/// \param port 串口端口
	/// \retval 0  打开成功
	/// \retval <0  打开失败
	int (*open)(struct CommPort *thiz);


	/// 关闭串口设备，当前读写操作立即返回，关闭后标准输入输出可以使用串口。
	/// 
	/// \param thiz 串口接口指针
	/// \retval 0  关闭成功
	/// \retval <0  关闭失败
	int (*close)(struct CommPort *thiz);

	/// 获取串口能力。
	/// 
	/// \param thiz 串口接口指针
	/// \param caps 串口能力结构指针
	/// \retval 0  获取成功
	/// \retval <0  获取失败
	int (*getCaps)(struct CommPort *thiz, CommCaps *caps);


	/// 设置串口属性。
	/// 
	/// \param thiz 串口接口指针
	/// \param [in] pAttr 指向串口属性结构COMM_ATTR的指针。
	/// \retval 0  关闭成功
	/// \retval <0  关闭失败
	int (*setAttribute)(struct CommPort *thiz, CommAttribute * attr);


	/// 读串口数据，一直等到读出指定的字节或出错时才返回，否则阻塞。
	/// 
	/// \param thiz 串口接口指针
	/// \param [out] buf 数据缓冲的指针。
	/// \param [in] len 要读出的字节数
	/// \retval >0  读出的字节数
	/// \retval <=0 读失败
	int (*read)(struct CommPort *thiz, void* buf, ulong len);


	/// 写串口数据，一直等到写入指定的字节或出错时才返回，否则阻塞。
	/// 
	/// \param thiz 串口接口指针
	/// \param [in] buf 数据缓冲的指针。
	/// \param [in] len 要写入的字节数
	/// \retval >0  写入的字节数
	/// \retval <=0 写失败
	int (*write)(struct CommPort *thiz, void* buf, ulong len);


	/// 中止串口读写操作或清空输入输出缓冲。
	/// 
	/// \param thiz 串口接口指针
	/// \param [in] dwFlags 要执行的操作,可以是下表中一个或多个值。
	/// \retval 0  操作成功
	/// \retval <0  操作失败
	int (*purge)(struct CommPort *thiz, ulong flags);


	/// 保留字节
	void* reserved[118];
} CommPort;


/// 串口接口描述结构，128字节
typedef struct CommPortDesc
{
	int port;			///< 物理端口号
	int card;			///< 子卡槽位号，0表示主板，>0表示子卡
	int reserved[30];	///< 保留字节
} CommPortDesc;


/// 创建串口接口
///
/// \param [in] desc 串口接口描述结构CommPortDesc指针
/// \param [out] commPort 串口接口指针的指针
/// \retval 0  连接成功。
/// \retval <0  连接失败。
int PAL_API createCommPort(CommPortDesc *desc, CommPort **commPort);


/// 得到串口数目
///
/// \retval 串口数目。
int PAL_API getCommPortCount(void);

/// @} end of group

#ifdef __cplusplus
}
#endif

#endif //__COMM_API_H__

